Custom Sources API Documentation

Base URL: https://api.chataid.com

Authorization: All endpoints require a valid Authorization: <YOUR_API_KEY> header. Your API key must be having the permission to interact with these APIs.

---

1. List Custom Sources

GET /external/sources/custom

Retrieve a paginated list of custom sources for your organisation. Supports filtering and pagination.

Query Parameters

Name	Type	Required	Description
name	string	Optional	Filter by source name (partial, case-insensitive)
status	string	Optional	Filter by source status
type	string	Optional	Filter by source type
adminId	string	Optional	Filter by admin Mongo ID
teamId	string	Optional	Filter by team Mongo ID
createdAtFrom	string	Optional	Filter by createdAt start date (ISO8601)
createdAtTo	string	Optional	Filter by createdAt end date (ISO8601)
page	number	Optional	Page number (default: 1)
pageSize	number	Optional	Page size (default: 100, max: 1000)

Example cURL

curl -X GET "https://api.chataid.com/external/sources/custom?page=1&pageSize=10" \
  -H "Authorization: <YOUR_API_KEY>"

Success Response

• Status: 200 OK
• Body:

{
  "ok": true,
  "data": [
    {
      "id": "string",
      "name": "string",
      "status": "string",
      "type": "string",
      "url": "string",
      "adminIds": ["string"],
      "teamIds": ["string"],
      "description": {
        "ai": "string",
        "user": "string"
      },
      "error": "string",
      "createdAt": "string",
      "lastTrainingStartedAt": "string",
      "lastTrainingAttemptedAt": "string",
      "lastTrainType": "string",
      "wordCount": "number",
      "usageCounts": "number"
    }
  ],
  "page": 1,
  "pageSize": 100,
  "total": 1,
  "totalPages": 1
}

---

2. Get Custom Source by ID

GET /external/sources/custom/:id

Retrieve a single custom source by its ID.

URL Parameters

Name	Type	Required	Description
id	string	Required	The custom source Mongo ID

Example cURL

curl -X GET "https://api.chataid.com/external/sources/custom/<SOURCE_ID>" \
  -H "Authorization: <YOUR_API_KEY>"

Success Response

• Status: 200 OK
• Body:

{
  "ok": true,
  "data": {
    "id": "string",
    "name": "string",
    "status": "string",
    "type": "string",
    "url": "string",
    "adminIds": ["string"],
    "teamIds": ["string"],
    "description": {
      "ai": "string",
      "user": "string"
    },
    "error": "string",
    "createdAt": "string",
    "lastTrainingStartedAt": "string",
    "lastTrainingAttemptedAt": "string",
    "lastTrainType": "string",
    "wordCount": "number",
    "usageCounts": "number"
  }
}

Error Response

• Status: 404 Not Found
• Body:

{
  "ok": false,
  "message": "Custom source not found"
}

---

3. Add Custom Sources (File Upload)

POST /external/sources/custom

Add new custom sources by uploading one or more files.

This endpoint requires a multipart/form-data request. Use the files field to upload one or more files.

Query Parameters

Name	Type	Required	Description
teamId	string	Optional	The Mongo ID of the Team where you want to add the sources

Body (multipart/form-data)

Field	Type	Required	Description
files	File[]	Required	One or more files to upload

Supported File Formats

The following file formats are supported for upload:

• PDF (.pdf)
• Microsoft Word (.doc, .docx)
• Microsoft PowerPoint (.ppt, .pptx)
• Microsoft Excel (.xls, .xlsx)
• Text (.txt)
• Markdown (.md)
• CSV (.csv)
• HTML (.html)
• Rich Text Format (.rtf)
• Images (.png, .jpg, .jpeg, .gif)

Example cURL

curl -X POST "https://api.chataid.com/external/sources/custom?teamId=<TEAM_ID>" \
  -H "Authorization: <YOUR_API_KEY>" \
  -F "files=@/path/to/file1.pdf" \
  -F "files=@/path/to/file2.docx"

Success Response

• Status: 200 OK
• Body:

{
  "ok": true,
  "message": "Started training on X sources successfully."
}

Error Response

• Status: 400 Bad Request
• Body:

{
  "ok": false,
  "message": "Error message (e.g., unsupported file type, already added, etc.)"
}

---

4. Delete Multiple Custom Sources

DELETE /external/sources/custom

Delete multiple custom sources by IDs or by filters.

You can pass either ids or filters in the request body:

• ids: Deletes the specific documents with those IDs.
• filters: Deletes all documents matching the filter criteria.

If neither is provided, all custom sources from your organisation will be deleted.

Body (JSON)

Field	Type	Required	Description
ids	array	Optional	Array of custom source document IDs to delete. Deletes only these documents.
filters	object	Optional	Filter object to select sources to delete. Deletes all documents matching the filter.

Filter Object Fields

Field	Type	Required	Description
name	string	Optional	Filter by document name
status	string	Optional	Filter by document status
type	string	Optional	Filter by document type
adminId	string	Optional	Filter by admin user ID
teamId	string	Optional	Filter by team ID
createdAtFrom	string	Optional	Filter by created at from (ISO8601)
createdAtTo	string	Optional	Filter by created at to (ISO8601)

Example cURLs

Delete by IDs:

curl -X DELETE "https://api.chataid.com/external/sources/custom" \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["id1", "id2"]}'

Delete by Filters:

curl -X DELETE "https://api.chataid.com/external/sources/custom" \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"status": "error"}}'

Success Response

• Status: 200 OK
• Body:

{
  "ok": true,
  "deletedCount": 25
}

---

5. Delete Custom Source by ID

DELETE /external/sources/custom/:id

Delete a single custom source by its ID.

URL Parameters

Name	Type	Required	Description
id	string	Required	The custom source Mongo ID

Example cURL

curl -X DELETE "https://api.chataid.com/external/sources/custom/<SOURCE_ID>" \
  -H "Authorization: <YOUR_API_KEY>"

Success Response

• Status: 200 OK
• Body:

{
  "ok": true
}

---

Common Errors

• 401 Unauthorized: Authentication required.
• 403 Forbidden: Your API Key do not have permission to access this resource.
• 404 Not Found: Resource not found.
• 400 Bad Request: Invalid input or parameters.

---